<html>
    <head>
    <link rel="stylesheet" href="lmm.css" type="text/css" />
    </head>
<body class="lmm">
<!-- This file is part of the Lisp Machine Manual.  -*-Text-*- -->
<!-- Function Description: Numbers -->
.c
<!-- TRUE and FALSE omitted; unclear why LMNUC thinks they belong here. -->
<!-- FALSE at least does not seem to be on SYSTEM package. -->
.c
<!-- Missing explanation of the random number algorithm.  -->
.c
<div class='chapter' id='9'>9. Numbers</div><p class='cindent' id='number'><!-- number -->
Lisp Machine Lisp includes several types of numbers, with different
characteristics.  Most numeric functions will accept any type of numbers as
arguments and do the right thing.  That is to say, they are <!-- open: 1, close: 0 --><font class="italic">generic</font><!-- open: 1, close: 1 --> <!-- MATCHED MATCHED MATCHED -->.
In Maclisp, there are generic numeric functions (like <!-- open: 2, close: 1 --><font class="lisp">plus</font><!-- open: 2, close: 2 --> <!-- MATCHED MATCHED MATCHED -->) and there
are specific numeric functions (like <!-- open: 3, close: 2 --><font class="lisp">+</font><!-- open: 3, close: 3 --> <!-- MATCHED MATCHED MATCHED -->) which only operate on a certain
type.  In Lisp Machine Lisp, this distinction does not exist; both function
names exist for compatibility but they are identical.  The microprogrammed
structure of the machine makes it possible to have only the generic
functions without loss of efficiency. 

The types of numbers in Lisp Machine Lisp are:
<table>
<tr valign='top'>
<td><font class='lisp'> fixnum</font></td><td>Fixnums are 24-bit 2's complement binary integers.  These are the "preferred,
most efficient" type of number.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> bignum</font></td><td>Bignums are arbitrary-precision binary integers.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> flonum</font></td><td>Flonums are floating-point numbers.  They have a mantissa of 32 bits and an exponent
of 11 bits, providing a precision of about 9 digits and a range of about 10^300.
Stable rounding is employed.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> small-flonum</font></td><td>Small flonums are another form of floating-point number, with a mantissa of
18 bits and an exponent of 7 bits, providing a precision of about 5 digits
and a range of about 10^19.  Small flonums are useful because, like fixnums,
they don't require any storage.  Computing with small flonums is
more efficient than with regular flonums.
</td></tr><!-- item_ --></table><!-- end table -->


Numbers are different from other objects in that they don't "have
identity." To put it another way, <!-- open: 4, close: 3 --><font class="lisp">eq</font><!-- open: 4, close: 4 --> <!-- MATCHED MATCHED MATCHED --> does not work on them.
Numbers do not behave "like objects." Fixnums and small flonums are
exceptions to this rule; some system code knows that <!-- open: 5, close: 4 --><font class="lisp">eq</font><!-- open: 5, close: 5 --> <!-- MATCHED MATCHED MATCHED --> works on
fixnums used to represent characters or small integers, and uses
<!-- open: 6, close: 5 --><font class="lisp">memq</font><!-- open: 6, close: 6 --> <!-- MATCHED MATCHED MATCHED --> or <!-- open: 7, close: 6 --><font class="lisp">assq</font><!-- open: 7, close: 7 --> <!-- MATCHED MATCHED MATCHED --> on them.

The Lisp machine automatically converts between fixnums and bignums
as necessary when computing with integers.  That is, if the result
of a computation with fixnums is too large to be represented as a fixnum,
it will be represented as a bignum.  If the result of a computation
with bignums is small enough to be represented as a fixnum, it will be.

The Lisp machine never automatically converts between flonums and small
flonums, since this would lead  either to inefficiency or to unexpected
numerical inaccuracies.  The user controls whether floating-point
calculations are done in large or small precision by the type of the
original input data.

Integer computations cannot "overflow", except for division by zero,
since bignums can be of arbitrary size.  Floating-point computations
can get exponent overflow or underflow, if the result is too large or small
to be represented.  This will signal an error.

When an arithmetic function of more than one argument is given arguments of
different numeric types, uniform <!-- open: 8, close: 7 --><font class="italic">coercion rules</font><!-- open: 8, close: 8 --> <!-- MATCHED MATCHED MATCHED --> are followed to convert
the arguments to a common type, which is also the type of the result (for
functions which return a number).  When a fixnum meets a bignum, the result
is (usually) a bignum.  When a fixnum or a bignum meets a small flonum or a flonum,
the result is a small flonum or a flonum (respectively).  When a small flonum
meets a regular flonum, the result is a regular flonum.

Unlike Maclisp, Lisp Machine Lisp does not have number declarations in the compiler.
Note that because fixnums and small flonums are "inums" (require no associated
storage) they are as efficient as declared numbers in Maclisp.

The different types of numbers are distinguished by their printed
representations.  A leading or embedded decimal point, and/or an exponent
separated by "e", indicates a flonum.  If a number has an exponent
separated by "s", it is a small flonum.  Small flonums require a special
indicator so that naive users will not be accidentally tricked into
computing with the lesser precision.  Fixnums and bignums have similar
printed representations; the number is a bignum if it is too big to be a
fixnum. 

<div class='section' id='9.1'>9.1 Numeric Predicates</div><div class='defun' id='zerop'>
  <font class='exdent'>
    <font class='funcname'>zerop </font>
    <font class='italic' color='purple'>x</font>
  </font><br>
Returns <!-- open: 9, close: 8 --><font class="lisp">t</font><!-- open: 9, close: 9 --> <!-- MATCHED MATCHED MATCHED --> if <!-- open: 10, close: 9 --><font class="italic">x</font><!-- open: 10, close: 10 --> <!-- MATCHED MATCHED MATCHED --> is zero.  Otherwise it returns <!-- open: 11, close: 10 --><font class="lisp">nil</font><!-- open: 11, close: 11 --> <!-- MATCHED MATCHED MATCHED -->.
If <!-- open: 12, close: 11 --><font class="italic">x</font><!-- open: 12, close: 12 --> <!-- MATCHED MATCHED MATCHED --> is not a number, <!-- open: 13, close: 12 --><font class="lisp">zerop</font><!-- open: 13, close: 13 --> <!-- MATCHED MATCHED MATCHED --> causes an error.
</div>

<div class='defun' id='plusp'>
  <font class='exdent'>
    <font class='funcname'>plusp </font>
    <font class='italic' color='purple'>x</font>
  </font><br>
Returns <!-- open: 14, close: 13 --><font class="lisp">t</font><!-- open: 14, close: 14 --> <!-- MATCHED MATCHED MATCHED --> if its argument is a positive number, strictly greater
than zero.  Otherwise it returns <!-- open: 15, close: 14 --><font class="lisp">nil</font><!-- open: 15, close: 15 --> <!-- MATCHED MATCHED MATCHED -->.
If <!-- open: 16, close: 15 --><font class="italic">x</font><!-- open: 16, close: 16 --> <!-- MATCHED MATCHED MATCHED --> is not a number, <!-- open: 17, close: 16 --><font class="lisp">plusp</font><!-- open: 17, close: 17 --> <!-- MATCHED MATCHED MATCHED --> causes an error.
</div>

<div class='defun' id='minusp'>
  <font class='exdent'>
    <font class='funcname'>minusp </font>
    <font class='italic' color='purple'>x</font>
  </font><br>
Returns <!-- open: 18, close: 17 --><font class="lisp">t</font><!-- open: 18, close: 18 --> <!-- MATCHED MATCHED MATCHED --> if its argument is a negative number, strictly
less than zero.  Otherwise it returns <!-- open: 19, close: 18 --><font class="lisp">nil</font><!-- open: 19, close: 19 --> <!-- MATCHED MATCHED MATCHED -->.
If <!-- open: 20, close: 19 --><font class="italic">x</font><!-- open: 20, close: 20 --> <!-- MATCHED MATCHED MATCHED --> is not a number, <!-- open: 21, close: 20 --><font class="lisp">minusp</font><!-- open: 21, close: 21 --> <!-- MATCHED MATCHED MATCHED --> causes an error.
</div>

<div class='defun' id='oddp'>
  <font class='exdent'>
    <font class='funcname'>oddp </font>
    <font class='italic' color='purple'>number</font>
  </font><br>
Returns <!-- open: 22, close: 21 --><font class="lisp">t</font><!-- open: 22, close: 22 --> <!-- MATCHED MATCHED MATCHED --> if <!-- open: 23, close: 22 --><font class="italic">number</font><!-- open: 23, close: 23 --> <!-- MATCHED MATCHED MATCHED --> is odd, otherwise <!-- open: 24, close: 23 --><font class="lisp">nil</font><!-- open: 24, close: 24 --> <!-- MATCHED MATCHED MATCHED -->.
If <!-- open: 25, close: 24 --><font class="italic">number</font><!-- open: 25, close: 25 --> <!-- MATCHED MATCHED MATCHED --> is not a fixnum or a bignum, <!-- open: 26, close: 25 --><font class="lisp">oddp</font><!-- open: 26, close: 26 --> <!-- MATCHED MATCHED MATCHED --> causes an error.
</div>

<div class='defun' id='evenp'>
  <font class='exdent'>
    <font class='funcname'>evenp </font>
    <font class='italic' color='purple'>number</font>
  </font><br>
Returns <!-- open: 27, close: 26 --><font class="lisp">t</font><!-- open: 27, close: 27 --> <!-- MATCHED MATCHED MATCHED --> if <!-- open: 28, close: 27 --><font class="italic">number</font><!-- open: 28, close: 28 --> <!-- MATCHED MATCHED MATCHED --> is even, otherwise <!-- open: 29, close: 28 --><font class="lisp">nil</font><!-- open: 29, close: 29 --> <!-- MATCHED MATCHED MATCHED -->.
If <!-- open: 30, close: 29 --><font class="italic">number</font><!-- open: 30, close: 30 --> <!-- MATCHED MATCHED MATCHED --> is not a fixnum or a bignum, <!-- open: 31, close: 30 --><font class="lisp">evenp</font><!-- open: 31, close: 31 --> <!-- MATCHED MATCHED MATCHED --> causes an error.
</div>

<div class='defspec' id='signp'><font class='exdent'><font class='funcname' id='signp'>signp</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent --><!-- open: 32, close: 31 --><font class="italic">signp</font><!-- open: 32, close: 32 --> <!-- MATCHED MATCHED MATCHED --> is used to test the sign of a number.  It is present
only for Maclisp compatibility, and is not recommended for use in new
programs.  <!-- open: 33, close: 32 --><font class="lisp">(signp <!-- open: 34, close: 32 --><font class="italic">test x</font><!-- open: 34, close: 33 -->)</font><!-- open: 34, close: 34 --> <!-- MATCHED MATCHED MATCHED --> returns <!-- open: 35, close: 34 --><font class="lisp">t</font><!-- open: 35, close: 35 --> <!-- MATCHED MATCHED MATCHED --> if <!-- open: 36, close: 35 --><font class="italic">x</font><!-- open: 36, close: 36 --> <!-- MATCHED MATCHED MATCHED --> is a number
which satisfies the <!-- open: 37, close: 36 --><font class="italic">test</font><!-- open: 37, close: 37 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 38, close: 37 --><font class="lisp">nil</font><!-- open: 38, close: 38 --> <!-- MATCHED MATCHED MATCHED --> if it is not.  <!-- open: 39, close: 38 --><font class="italic">test</font><!-- open: 39, close: 39 --> <!-- MATCHED MATCHED MATCHED --> is not
evaluated, but <!-- open: 40, close: 39 --><font class="italic">x</font><!-- open: 40, close: 40 --> <!-- MATCHED MATCHED MATCHED --> is.
<!-- open: 41, close: 40 --><font class="italic">test</font><!-- open: 41, close: 41 --> <!-- MATCHED MATCHED MATCHED --> can be one of the following:
<table>
<tr valign='top'>
<td><font class='lisp'> l</font></td><td>x &lt; 0
</td></tr>
<tr valign='top'>
<td><font class='lisp'> le</font></td><td>x &le; 0
</td></tr>
<tr valign='top'>
<td><font class='lisp'> e</font></td><td>x = 0
</td></tr>
<tr valign='top'>
<td><font class='lisp'> n</font></td><td>x &ne; 0
</td></tr>
<tr valign='top'>
<td><font class='lisp'> ge</font></td><td>x &ge; 0
</td></tr>
<tr valign='top'>
<td><font class='lisp'> g</font></td><td>x &gt; 0
</td></tr><!-- item_ --></table><!-- end table -->

<pre class='lisp'>
<font class='exdent'>Examples:
</font><!-- exdent -->(signp le 12) =&gt; t
(signp n 0) =&gt; nil
(signp g 'foo) =&gt; nil
</pre>
</div>

See also the data-type predicates <!-- open: 42, close: 41 --><font class="lisp">fixp</font><!-- open: 42, close: 42 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 43, close: 42 --><font class="lisp">floatp</font><!-- open: 43, close: 43 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 44, close: 43 --><font class="lisp">bigp</font><!-- open: 44, close: 44 --> <!-- MATCHED MATCHED MATCHED -->,
<!-- open: 45, close: 44 --><font class="lisp">small-floatp</font><!-- open: 45, close: 45 --> <!-- MATCHED MATCHED MATCHED -->, and <!-- open: 46, close: 45 --><font class="lisp">numberp</font><!-- open: 46, close: 46 --> <!-- MATCHED MATCHED MATCHED --> (<font color='red'>LINK:(</font>fixp-fun)).

All of these functions require that their arguments be numbers, and signal
an error if given a non-number.  They work on all types of numbers,
automatically performing any required coercions.

<div class='defun' id='='>
  <font class='exdent'>
    <font class='funcname'>= </font>
    <font class='italic' color='purple'>x y</font>
  </font><br>
Returns <!-- open: 47, close: 46 --><font class="lisp">t</font><!-- open: 47, close: 47 --> <!-- MATCHED MATCHED MATCHED --> if <!-- open: 48, close: 47 --><font class="italic">x</font><!-- open: 48, close: 48 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 49, close: 48 --><font class="italic">y</font><!-- open: 49, close: 49 --> <!-- MATCHED MATCHED MATCHED --> are numerically equal.
</div>

<div class='defun' id='greaterp'>
  <font class='exdent'>
    <font class='funcname'>greaterp </font>
    <font class='italic' color='purple'>x y &rest more-args</font>
  </font><br>
<!-- open: 50, close: 49 --><font class="lisp">greaterp</font><!-- open: 50, close: 50 --> <!-- MATCHED MATCHED MATCHED --> compares its arguments from left to right.  If any argument
is not greater than the next, <!-- open: 51, close: 50 --><font class="lisp">greaterp</font><!-- open: 51, close: 51 --> <!-- MATCHED MATCHED MATCHED --> returns <!-- open: 52, close: 51 --><font class="lisp">nil</font><!-- open: 52, close: 52 --> <!-- MATCHED MATCHED MATCHED -->.  But if the
arguments are monotonically strictly decreasing, the result is <!-- open: 53, close: 52 --><font class="lisp">t</font><!-- open: 53, close: 53 --> <!-- MATCHED MATCHED MATCHED -->.
<pre class='lisp'>
<font class='exdent'>Examples:
</font><!-- exdent -->(greaterp 4 3) =&gt; t
(greaterp 4 3 2 1 0) =&gt; t
(greaterp 4 3 1 2 0) =&gt; nil
</pre>
</div>

<div class='defun' id='>'>
  <font class='exdent'>
    <font class='funcname'>> </font>
    <font class='italic' color='purple'>x y</font>
  </font><br>
Returns <!-- open: 54, close: 53 --><font class="lisp">t</font><!-- open: 54, close: 54 --> <!-- MATCHED MATCHED MATCHED --> if <!-- open: 55, close: 54 --><font class="italic">x</font><!-- open: 55, close: 55 --> <!-- MATCHED MATCHED MATCHED --> is strictly greater than <!-- open: 56, close: 55 --><font class="italic">y</font><!-- open: 56, close: 56 --> <!-- MATCHED MATCHED MATCHED -->, and <!-- open: 57, close: 56 --><font class="lisp">nil</font><!-- open: 57, close: 57 --> <!-- MATCHED MATCHED MATCHED -->
otherwise.
</div>

<div class='defmac' id='>= x y'><font class='exdent'><font class='funcname' id='>= x y'>>= x y</font><font class="italic"> Macro</font></br></font><!-- end font_exdent --></div><div class='defmac id='&ge; x y''><font class='exdent'><font class='funcname' id='&ge; x y'>&ge; x y</font><font class="italic"> Macro</font><br></font><!-- end font_exdent -->Returns <!-- open: 58, close: 57 --><font class="lisp">t</font><!-- open: 58, close: 58 --> <!-- MATCHED MATCHED MATCHED --> if <!-- open: 59, close: 58 --><font class="italic">x</font><!-- open: 59, close: 59 --> <!-- MATCHED MATCHED MATCHED --> is greater than or equal to <!-- open: 60, close: 59 --><font class="italic">y</font><!-- open: 60, close: 60 --> <!-- MATCHED MATCHED MATCHED -->, and <!-- open: 61, close: 60 --><font class="lisp">nil</font><!-- open: 61, close: 61 --> <!-- MATCHED MATCHED MATCHED -->
otherwise.
</div>

<div class='defun' id='lessp'>
  <font class='exdent'>
    <font class='funcname'>lessp </font>
    <font class='italic' color='purple'>x y &rest more-args</font>
  </font><br>
<!-- open: 62, close: 61 --><font class="lisp">lessp</font><!-- open: 62, close: 62 --> <!-- MATCHED MATCHED MATCHED --> compares its arguments from left to right.  If any argument
is not less than the next, <!-- open: 63, close: 62 --><font class="lisp">lessp</font><!-- open: 63, close: 63 --> <!-- MATCHED MATCHED MATCHED --> returns <!-- open: 64, close: 63 --><font class="lisp">nil</font><!-- open: 64, close: 64 --> <!-- MATCHED MATCHED MATCHED -->.  But if the
arguments are monotonically strictly increasing, the result is <!-- open: 65, close: 64 --><font class="lisp">t</font><!-- open: 65, close: 65 --> <!-- MATCHED MATCHED MATCHED -->.
<pre class='lisp'>
<font class='exdent'>Examples:
</font><!-- exdent -->(lessp 3 4) =&gt; t
(lessp 1 1) =&gt; nil
(lessp 0 1 2 3 4) =&gt; t
(lessp 0 1 3 2 4) =&gt; nil
</pre>
</div>

<div class='defun' id='<'>
  <font class='exdent'>
    <font class='funcname'>< </font>
    <font class='italic' color='purple'>x y</font>
  </font><br>
Returns <!-- open: 66, close: 65 --><font class="lisp">t</font><!-- open: 66, close: 66 --> <!-- MATCHED MATCHED MATCHED --> if <!-- open: 67, close: 66 --><font class="italic">x</font><!-- open: 67, close: 67 --> <!-- MATCHED MATCHED MATCHED --> is strictly less than <!-- open: 68, close: 67 --><font class="italic">y</font><!-- open: 68, close: 68 --> <!-- MATCHED MATCHED MATCHED -->, and <!-- open: 69, close: 68 --><font class="lisp">nil</font><!-- open: 69, close: 69 --> <!-- MATCHED MATCHED MATCHED -->
otherwise.
</div>

<div class='defmac' id='<= x y'><font class='exdent'><font class='funcname' id='<= x y'><= x y</font><font class="italic"> Macro</font></br></font><!-- end font_exdent --></div><div class='defmac id='&le; x y''><font class='exdent'><font class='funcname' id='&le; x y'>&le; x y</font><font class="italic"> Macro</font><br></font><!-- end font_exdent -->Returns <!-- open: 70, close: 69 --><font class="lisp">t</font><!-- open: 70, close: 70 --> <!-- MATCHED MATCHED MATCHED --> if <!-- open: 71, close: 70 --><font class="italic">x</font><!-- open: 71, close: 71 --> <!-- MATCHED MATCHED MATCHED --> is less than or equal to <!-- open: 72, close: 71 --><font class="italic">y</font><!-- open: 72, close: 72 --> <!-- MATCHED MATCHED MATCHED -->, and <!-- open: 73, close: 72 --><font class="lisp">nil</font><!-- open: 73, close: 73 --> <!-- MATCHED MATCHED MATCHED -->
otherwise.
</div>

<div class='defmac' id='&ne; x y'><font class='exdent'><font class='funcname' id='&ne; x y'>&ne; x y</font><font class="italic"> Macro</font></br></font><!-- end font_exdent -->Returns <!-- open: 74, close: 73 --><font class="lisp">t</font><!-- open: 74, close: 74 --> <!-- MATCHED MATCHED MATCHED --> if <!-- open: 75, close: 74 --><font class="italic">x</font><!-- open: 75, close: 75 --> <!-- MATCHED MATCHED MATCHED --> is not equal to <!-- open: 76, close: 75 --><font class="italic">y</font><!-- open: 76, close: 76 --> <!-- MATCHED MATCHED MATCHED -->, and <!-- open: 77, close: 76 --><font class="lisp">nil</font><!-- open: 77, close: 77 --> <!-- MATCHED MATCHED MATCHED --> otherwise.
</div>

<div class='section' id='9.2'>9.2 Arithmetic</div>
All of these functions require that their arguments be numbers, and signal
an error if given a non-number.  They work on all types of numbers,
automatically performing any required coercions.

<div class='defun' id='plus'>
  <font class='exdent'>
    <font class='funcname'>plus </font>
    <font class='italic' color='purple'>&rest args</font>
  </font><br>
</div><div class='defun1' id='+'>
<font class='exdent'><font class='funcname'>+ </font><font class='italic' color='purple'>&rest args
</font></font><br></div><div class='defun1' id='+$'>
<font class='exdent'><font class='funcname'>+$ </font><font class='italic' color='purple'>&rest args
</font></font><br>Returns the sum of its arguments.  If there are no arguments, it returns
0, which is the identity for this operation.
</div>

<div class='defun' id='difference'>
  <font class='exdent'>
    <font class='funcname'>difference </font>
    <font class='italic' color='purple'>arg &rest args</font>
  </font><br>
Returns its first argument minus all of the rest of its arguments.
</div>

<div class='defun' id='-'>
  <font class='exdent'>
    <font class='funcname'>- </font>
    <font class='italic' color='purple'>arg &rest args</font>
  </font><br>
</div><div class='defun1' id='-$'>
<font class='exdent'><font class='funcname'>-$ </font><font class='italic' color='purple'>arg &rest args
</font></font><br>With only one argument, <!-- open: 78, close: 77 --><font class="lisp">-</font><!-- open: 78, close: 78 --> <!-- MATCHED MATCHED MATCHED --> is the same as <!-- open: 79, close: 78 --><font class="lisp">minus</font><!-- open: 79, close: 79 --> <!-- MATCHED MATCHED MATCHED -->; it
returns the negative of its argument.
With more than one argument, <!-- open: 80, close: 79 --><font class="lisp">-</font><!-- open: 80, close: 80 --> <!-- MATCHED MATCHED MATCHED --> is the same as <!-- open: 81, close: 80 --><font class="lisp">difference</font><!-- open: 81, close: 81 --> <!-- MATCHED MATCHED MATCHED -->;
it returns its first argument minus all of the rest of its arguments.
</div>

<div class='defun' id='times'>
  <font class='exdent'>
    <font class='funcname'>times </font>
    <font class='italic' color='purple'>&rest args</font>
  </font><br>
</div><div class='defun1' id='*'>
<font class='exdent'><font class='funcname'>* </font><font class='italic' color='purple'>&rest args
</font></font><br></div><div class='defun1' id='*$'>
<font class='exdent'><font class='funcname'>*$ </font><font class='italic' color='purple'>&rest args
</font></font><br>Returns the product of its arguments.  If there are no arguments, it
returns 1, which is the identity for this operation.
</div>

<div class='defun' id='quotient'>
  <font class='exdent'>
    <font class='funcname'>quotient </font>
    <font class='italic' color='purple'>arg &rest args</font>
  </font><br>
Returns the first argument divided by all of the rest of its arguments.
</div>

<div class='defun' id='//'>
  <font class='exdent'>
    <font class='funcname'>// </font>
    <font class='italic' color='purple'>arg &rest args</font>
  </font><br>
</div><div class='defun1' id='//$'>
<font class='exdent'><font class='funcname'>//$ </font><font class='italic' color='purple'>arg &rest args
</font></font><br>The name of this function is written <!-- open: 82, close: 81 --><font class="lisp">//</font><!-- open: 82, close: 82 --> <!-- MATCHED MATCHED MATCHED --> rather than <!-- open: 83, close: 82 --><font class="lisp">/</font><!-- open: 83, close: 83 --> <!-- MATCHED MATCHED MATCHED --> because
<!-- open: 84, close: 83 --><font class="lisp">/</font><!-- open: 84, close: 84 --> <!-- MATCHED MATCHED MATCHED --> is the quoting character in Lisp syntax and must be doubled.
With more than one argument, <!-- open: 85, close: 84 --><font class="lisp">//</font><!-- open: 85, close: 85 --> <!-- MATCHED MATCHED MATCHED --> is the same as <!-- open: 86, close: 85 --><font class="lisp">quotient</font><!-- open: 86, close: 86 --> <!-- MATCHED MATCHED MATCHED -->;
it returns the first argument divided by all of the rest of its arguments.
With only one argument, <!-- open: 87, close: 86 --><font class="lisp">(// <!-- open: 88, close: 86 --><font class="italic">x</font><!-- open: 88, close: 87 -->)</font><!-- open: 88, close: 88 --> <!-- MATCHED MATCHED MATCHED --> is the same as <!-- open: 89, close: 88 --><font class="lisp">(// 1 <!-- open: 90, close: 88 --><font class="italic">x</font><!-- open: 90, close: 89 -->)</font><!-- open: 90, close: 90 --> <!-- MATCHED MATCHED MATCHED -->.
<pre class='lisp'>
<font class='exdent'>Examples:
</font><!-- exdent -->(// 3 2) =&gt; 1       <!-- open: 91, close: 90 --><font class="main">;Fixnum division truncates.</font><!-- open: 91, close: 91 --> <!-- MATCHED MATCHED MATCHED -->
(// 3 2.0) =&gt; 1.5
(// 3 2.0s0) =&gt; 1.5s0
(// 4 2) =&gt; 2
(// 12. 2. 3.) =&gt; 2
</pre>
</div>

<div class='defun' id='add1'>
  <font class='exdent'>
    <font class='funcname'>add1 </font>
    <font class='italic' color='purple'>x</font>
  </font><br>
</div><div class='defun1' id='1+'>
<font class='exdent'><font class='funcname'>1+ </font><font class='italic' color='purple'>x
</font></font><br></div><div class='defun1' id='1+$'>
<font class='exdent'><font class='funcname'>1+$ </font><font class='italic' color='purple'>x
</font></font><br><!-- open: 92, close: 91 --><font class="lisp">(add1 x)</font><!-- open: 92, close: 92 --> <!-- MATCHED MATCHED MATCHED --> is the same as <!-- open: 93, close: 92 --><font class="lisp">(plus x 1)</font><!-- open: 93, close: 93 --> <!-- MATCHED MATCHED MATCHED -->.
</div>

<div class='defun' id='sub1'>
  <font class='exdent'>
    <font class='funcname'>sub1 </font>
    <font class='italic' color='purple'>x</font>
  </font><br>
</div><div class='defun1' id='1-'>
<font class='exdent'><font class='funcname'>1- </font><font class='italic' color='purple'>x
</font></font><br></div><div class='defun1' id='1-$'>
<font class='exdent'><font class='funcname'>1-$ </font><font class='italic' color='purple'>x
</font></font><br><!-- open: 94, close: 93 --><font class="lisp">(sub1 x)</font><!-- open: 94, close: 94 --> <!-- MATCHED MATCHED MATCHED --> is the same as <!-- open: 95, close: 94 --><font class="lisp">(difference x 1)</font><!-- open: 95, close: 95 --> <!-- MATCHED MATCHED MATCHED -->.  Note that the
short name may be confusing: <!-- open: 96, close: 95 --><font class="lisp">(1- x)</font><!-- open: 96, close: 96 --> <!-- MATCHED MATCHED MATCHED --> does <!-- open: 97, close: 96 --><font class="italic">not</font><!-- open: 97, close: 97 --> <!-- MATCHED MATCHED MATCHED --> mean 1-x;
rather, it means x-1.
</div>

<div class='defun' id='remainder'>
  <font class='exdent'>
    <font class='funcname'>remainder </font>
    <font class='italic' color='purple'>x y</font>
  </font><br>
</div><div class='defun1' id='\'>
<font class='exdent'><font class='funcname'>\ </font><font class='italic' color='purple'>x y
</font></font><br>Returns the remainder of <!-- open: 98, close: 97 --><font class="italic">x</font><!-- open: 98, close: 98 --> <!-- MATCHED MATCHED MATCHED --> divided by <!-- open: 99, close: 98 --><font class="italic">y</font><!-- open: 99, close: 99 --> <!-- MATCHED MATCHED MATCHED -->.
<!-- open: 100, close: 99 --><font class="italic">x</font><!-- open: 100, close: 100 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 101, close: 100 --><font class="italic">y</font><!-- open: 101, close: 101 --> <!-- MATCHED MATCHED MATCHED --> may not be flonums nor small flonums.
</div>

<div class='defun' id='gcd'>
  <font class='exdent'>
    <font class='funcname'>gcd </font>
    <font class='italic' color='purple'>x y</font>
  </font><br>
</div><div class='defun1' id='\\'>
<font class='exdent'><font class='funcname'>\\ </font><font class='italic' color='purple'>x y
</font></font><br>Returns the greatest common divisor of <!-- open: 102, close: 101 --><font class="italic">x</font><!-- open: 102, close: 102 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 103, close: 102 --><font class="italic">y</font><!-- open: 103, close: 103 --> <!-- MATCHED MATCHED MATCHED -->.
<!-- open: 104, close: 103 --><font class="italic">x</font><!-- open: 104, close: 104 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 105, close: 104 --><font class="italic">y</font><!-- open: 105, close: 105 --> <!-- MATCHED MATCHED MATCHED --> may not be flonums nor small flonums.
</div>

<div class='defun' id='expt'>
  <font class='exdent'>
    <font class='funcname'>expt </font>
    <font class='italic' color='purple'>x y</font>
  </font><br>
</div><div class='defun1' id='^'>
<font class='exdent'><font class='funcname'>^ </font><font class='italic' color='purple'>x y
</font></font><br></div><div class='defun1' id='^$'>
<font class='exdent'><font class='funcname'>^$ </font><font class='italic' color='purple'>x y
</font></font><br>Returns <!-- open: 106, close: 105 --><font class="italic">x</font><!-- open: 106, close: 106 --> <!-- MATCHED MATCHED MATCHED --> raised to the <!-- open: 107, close: 106 --><font class="italic">y</font><!-- open: 107, close: 107 --> <!-- MATCHED MATCHED MATCHED -->'th power.  <!-- open: 108, close: 107 --><font class="italic">y</font><!-- open: 108, close: 108 --> <!-- MATCHED MATCHED MATCHED --> must be a fixnum.
[I guess this is incompatible with Maclisp.]
</div>

<div class='defun' id='exp'>
  <font class='exdent'>
    <font class='funcname'>exp </font>
    <font class='italic' color='purple'>x</font>
  </font><br>
Returns <!-- open: 109, close: 108 --><font class="italic">e</font><!-- open: 109, close: 109 --> <!-- MATCHED MATCHED MATCHED --> raised to the <!-- open: 110, close: 109 --><font class="italic">x</font><!-- open: 110, close: 110 --> <!-- MATCHED MATCHED MATCHED -->'th power, where <!-- open: 111, close: 110 --><font class="italic">e</font><!-- open: 111, close: 111 --> <!-- MATCHED MATCHED MATCHED --> is the base of natural logarithms.
</div>

<div class='defun' id='log'>
  <font class='exdent'>
    <font class='funcname'>log </font>
    <font class='italic' color='purple'>x</font>
  </font><br>
Returns the natural logarithm of <!-- open: 112, close: 111 --><font class="italic">x</font><!-- open: 112, close: 112 --> <!-- MATCHED MATCHED MATCHED -->.
</div>

<div class='defun' id='sin'>
  <font class='exdent'>
    <font class='funcname'>sin </font>
    <font class='italic' color='purple'>x</font>
  </font><br>
Returns the sine of <!-- open: 113, close: 112 --><font class="italic">x</font><!-- open: 113, close: 113 --> <!-- MATCHED MATCHED MATCHED --> in radians.
</div>

<!-- bletch, do we want these in here? -->
<div class='defun' id='sind'>
  <font class='exdent'>
    <font class='funcname'>sind </font>
    <font class='italic' color='purple'>x</font>
  </font><br>
Returns the sine of <!-- open: 114, close: 113 --><font class="italic">x</font><!-- open: 114, close: 114 --> <!-- MATCHED MATCHED MATCHED --> in degrees.
</div>

<div class='defun' id='cos'>
  <font class='exdent'>
    <font class='funcname'>cos </font>
    <font class='italic' color='purple'>x</font>
  </font><br>
Returns the cosine of <!-- open: 115, close: 114 --><font class="italic">x</font><!-- open: 115, close: 115 --> <!-- MATCHED MATCHED MATCHED --> in radians.
</div>

<!-- bletch do we want these in here? -->
<div class='defun' id='cosd'>
  <font class='exdent'>
    <font class='funcname'>cosd </font>
    <font class='italic' color='purple'>x</font>
  </font><br>
Returns the cosine of <!-- open: 116, close: 115 --><font class="italic">x</font><!-- open: 116, close: 116 --> <!-- MATCHED MATCHED MATCHED --> in degrees.
</div>

<div class='defun' id='sqrt'>
  <font class='exdent'>
    <font class='funcname'>sqrt </font>
    <font class='italic' color='purple'>x</font>
  </font><br>
Returns the square root of <!-- open: 117, close: 116 --><font class="italic">x</font><!-- open: 117, close: 117 --> <!-- MATCHED MATCHED MATCHED -->.
</div>

<div class='defun' id='atan'>
  <font class='exdent'>
    <font class='funcname'>atan </font>
    <font class='italic' color='purple'>y x</font>
  </font><br>
Returns the arctangent of the angle <!-- open: 118, close: 117 --><font class="italic">y/x</font><!-- open: 118, close: 118 --> <!-- MATCHED MATCHED MATCHED -->. It always returns a
non-negative number between zero and &pi;/2.
</div>

<div class='defun' id='atan2'>
  <font class='exdent'>
    <font class='funcname'>atan2 </font>
    <font class='italic' color='purple'>y x</font>
  </font><br>
Returns the arctangent of the angle <!-- open: 119, close: 118 --><font class="italic">y/x</font><!-- open: 119, close: 119 --> <!-- MATCHED MATCHED MATCHED -->, except that it returns a
number between -&pi;/2 and &pi;/2.
</div>

<div class='defun' id='max'>
  <font class='exdent'>
    <font class='funcname'>max </font>
    <font class='italic' color='purple'>&rest args</font>
  </font><br>
<!-- open: 120, close: 119 --><font class="lisp">max</font><!-- open: 120, close: 120 --> <!-- MATCHED MATCHED MATCHED --> returns the largest of its arguments.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(max 1 3 2) =&gt; 3
</pre>
<!-- open: 121, close: 120 --><font class="lisp">max</font><!-- open: 121, close: 121 --> <!-- MATCHED MATCHED MATCHED --> requires at least one argument.
</div>

<div class='defun' id='min'>
  <font class='exdent'>
    <font class='funcname'>min </font>
    <font class='italic' color='purple'>&rest args</font>
  </font><br>
<!-- open: 122, close: 121 --><font class="lisp">min</font><!-- open: 122, close: 122 --> <!-- MATCHED MATCHED MATCHED --> returns the smallest of its arguments.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(min 1 3 2) =&gt; 1
</pre>
<!-- open: 123, close: 122 --><font class="lisp">min</font><!-- open: 123, close: 123 --> <!-- MATCHED MATCHED MATCHED --> requires at least one argument.
</div>

<div class='defun' id='abs'>
  <font class='exdent'>
    <font class='funcname'>abs </font>
    <font class='italic' color='purple'>x</font>
  </font><br>
Returns <!-- open: 124, close: 123 --><font class="lisp">|<!-- open: 125, close: 123 --><font class="italic">x</font><!-- open: 125, close: 124 -->|</font><!-- open: 125, close: 125 --> <!-- MATCHED MATCHED MATCHED -->, the absolute value of the number <!-- open: 126, close: 125 --><font class="italic">x</font><!-- open: 126, close: 126 --> <!-- MATCHED MATCHED MATCHED -->.
<!-- open: 127, close: 126 --><font class="lisp">abs</font><!-- open: 127, close: 127 --> <!-- MATCHED MATCHED MATCHED --> could have been defined by:
<pre class='lisp'>
(defun abs (x)
    (cond ((minusp x) (minus x))
	  (t x)))
</pre>
</div>

<div class='defun' id='minus'>
  <font class='exdent'>
    <font class='funcname'>minus </font>
    <font class='italic' color='purple'>x</font>
  </font><br>
Returns the negative of <!-- open: 128, close: 127 --><font class="italic">x</font><!-- open: 128, close: 128 --> <!-- MATCHED MATCHED MATCHED -->.
<pre class='lisp'>
<font class='exdent'>Examples:
</font><!-- exdent -->(minus 1) =&gt; -1
(minus -3) =&gt; 3
</pre>
</div>

<div class='defun' id='*dif'>
  <font class='exdent'>
    <font class='funcname'>*dif </font>
    <font class='italic' color='purple'>x y</font>
  </font><br>
</div><div class='defun1' id='*plus'>
<font class='exdent'><font class='funcname'>*plus </font><font class='italic' color='purple'>x y
</font></font><br></div><div class='defun1' id='*quo'>
<font class='exdent'><font class='funcname'>*quo </font><font class='italic' color='purple'>x y
</font></font><br></div><div class='defun1' id='*times'>
<font class='exdent'><font class='funcname'>*times </font><font class='italic' color='purple'>x y
</font></font><br>These are the internal micro-coded arithmetic functions.  There is no
reason why anyone should need to refer to these explicitly, since the
compiler knows how to generate the appropriate code for <!-- open: 129, close: 128 --><font class="lisp">plus</font><!-- open: 129, close: 129 --> <!-- MATCHED MATCHED MATCHED -->,
<!-- open: 130, close: 129 --><font class="lisp">+</font><!-- open: 130, close: 130 --> <!-- MATCHED MATCHED MATCHED -->, etc.  These names are only here for Maclisp compatibility.
</div>

The following functions are provided to allow specific conversions of data
types to be forced, when desired.

<div class='defun' id='fix'>
  <font class='exdent'>
    <font class='funcname'>fix </font>
    <font class='italic' color='purple'>x</font>
  </font><br>
Converts <!-- open: 131, close: 130 --><font class="italic">x</font><!-- open: 131, close: 131 --> <!-- MATCHED MATCHED MATCHED --> from a flonum (or small-flonum) to an integer, by truncation.
The result is a fixnum or a bignum as appropriate.  If <!-- open: 132, close: 131 --><font class="italic">x</font><!-- open: 132, close: 132 --> <!-- MATCHED MATCHED MATCHED --> is already
a fixnum or a bignum, it is returned unchanged.
</div>

<div class='defun' id='fixr'>
  <font class='exdent'>
    <font class='funcname'>fixr </font>
    <font class='italic' color='purple'>x</font>
  </font><br>
Converts <!-- open: 133, close: 132 --><font class="italic">x</font><!-- open: 133, close: 133 --> <!-- MATCHED MATCHED MATCHED --> from a flonum (or small-flonum) to an integer, by truncation.
</div>

<div class='defun' id='float'>
  <font class='exdent'>
    <font class='funcname'>float </font>
    <font class='italic' color='purple'>x</font>
  </font><br>
Converts <!-- open: 134, close: 133 --><font class="italic">x</font><!-- open: 134, close: 134 --> <!-- MATCHED MATCHED MATCHED --> to a flonum.  <!-- open: 135, close: 134 --><font class="italic">x</font><!-- open: 135, close: 135 --> <!-- MATCHED MATCHED MATCHED --> may be a fixnum, a bignum, a small-flonum,
or a flonum.
</div>

<div class='defun' id='small-float'>
  <font class='exdent'>
    <font class='funcname'>small-float </font>
    <font class='italic' color='purple'>x</font>
  </font><br>
Converts <!-- open: 136, close: 135 --><font class="italic">x</font><!-- open: 136, close: 136 --> <!-- MATCHED MATCHED MATCHED --> to a small flonum.  <!-- open: 137, close: 136 --><font class="italic">x</font><!-- open: 137, close: 137 --> <!-- MATCHED MATCHED MATCHED --> may be a fixnum, a bignum, a small-flonum,
or a flonum.
</div>

<!-- Lots of trig functions missing as of this writing.  -->

<div class='section' id='9.3'>9.3 Random Functions</div>
<div class='defun' id='random'>
  <font class='exdent'>
    <font class='funcname'>random </font>
    <font class='italic' color='purple'>&optional arg (array <!-- open: 138, close: 137 --><font class="lisp">si:random-array</font><!-- open: 138, close: 138 --> <!-- MATCHED MATCHED MATCHED -->)</font>
  </font><br>
<!-- open: 139, close: 138 --><font class="lisp">(random)</font><!-- open: 139, close: 139 --> <!-- MATCHED MATCHED MATCHED --> returns a random fixnum, positive or negative.
If <!-- open: 140, close: 139 --><font class="italic">arg</font><!-- open: 140, close: 140 --> <!-- MATCHED MATCHED MATCHED --> is present, a fixnum between 0 and <!-- open: 141, close: 140 --><font class="italic">arg</font><!-- open: 141, close: 141 --> <!-- MATCHED MATCHED MATCHED -->-1 inclusive is returned.
If <!-- open: 142, close: 141 --><font class="italic">array</font><!-- open: 142, close: 142 --> <!-- MATCHED MATCHED MATCHED --> is present, the given array is used instead of the default
one (see below).
[The random algorithm should be described.]
</div>

<div class='defun' id='si:random-create-array'>
  <font class='exdent'>
    <font class='funcname'>si:random-create-array </font>
    <font class='italic' color='purple'>size offset seed &optional (area <!-- open: 143, close: 142 --><font class="lisp">default-array-area</font><!-- open: 143, close: 143 --> <!-- MATCHED MATCHED MATCHED -->)</font>
  </font><br>
Creates, initializes and returns a random-number-generator array.
This is used for more advanced applications of the pseudo-random
number generator, in which it is desirable to have several different
controllable resettable sources of random numbers.  For the exact
meaning of the arguments, read the code.
<!-- For now. -->
<!-- open: 144, close: 143 --><font class="italic">size</font><!-- open: 144, close: 144 --> <!-- MATCHED MATCHED MATCHED --> is the size of the array, <!-- open: 145, close: 144 --><font class="italic">offset</font><!-- open: 145, close: 145 --> <!-- MATCHED MATCHED MATCHED --> is an integer less than
<!-- open: 146, close: 145 --><font class="italic">size</font><!-- open: 146, close: 146 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 147, close: 146 --><font class="italic">seed</font><!-- open: 147, close: 147 --> <!-- MATCHED MATCHED MATCHED --> is a fixnum.
This calls <!-- open: 148, close: 147 --><font class="lisp">si:random-initialize</font><!-- open: 148, close: 148 --> <!-- MATCHED MATCHED MATCHED --> on the random array before returning it.
</div>

<div class='defun' id='si:random-initialize'>
  <font class='exdent'>
    <font class='funcname'>si:random-initialize </font>
    <font class='italic' color='purple'>array</font>
  </font><br>
<!-- open: 149, close: 148 --><font class="italic">array</font><!-- open: 149, close: 149 --> <!-- MATCHED MATCHED MATCHED --> must be a random-number-generator array, such as
is created by <!-- open: 150, close: 149 --><font class="lisp">si:random-create-array</font><!-- open: 150, close: 150 --> <!-- MATCHED MATCHED MATCHED -->.  It reinitializes the
contents of the array from the seed (calling <!-- open: 151, close: 150 --><font class="lisp">random</font><!-- open: 151, close: 151 --> <!-- MATCHED MATCHED MATCHED --> changes
the contents of the array and the pointers, but not the seed).
</div>

<div class='defvar' id='si:random-array'><font class='exdent'><font class='funcname' id='si:random-array'>si:random-array</font><font class="italic"> Variable</font><br></font><!-- end font_exdent -->The value of <!-- open: 152, close: 151 --><font class="lisp">si:random-array</font><!-- open: 152, close: 152 --> <!-- MATCHED MATCHED MATCHED --> is the default random-number-generator array.
It is created if <!-- open: 153, close: 152 --><font class="lisp">random</font><!-- open: 153, close: 153 --> <!-- MATCHED MATCHED MATCHED --> is called and <!-- open: 154, close: 153 --><font class="lisp">si:random-array</font><!-- open: 154, close: 154 --> <!-- MATCHED MATCHED MATCHED --> is unbound.
A random-number-generator array has a leader which is a structure with
the following elements:
<table><!-- ftable -->
 3
<tr valign='top'><td colspan='2'><font class='lisp'> si:random-fill-pointer</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>The fill-pointer, the length of the array.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> si:random-seed</font></td><td>The seed from which to initialize the contents.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> si:random-pointer-1</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>The first pointer.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> si:random-pointer-2</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>The second pointer.
</td></tr><!-- item_ --></table><!-- end table -->

</div>

<div class='section' id='9.4'>9.4 Logical Operations on Numbers</div>
Except for <!-- open: 155, close: 154 --><font class="lisp">lsh</font><!-- open: 155, close: 155 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 156, close: 155 --><font class="lisp">rot</font><!-- open: 156, close: 156 --> <!-- MATCHED MATCHED MATCHED -->, these functions operate on either
fixnums or bignums.  <!-- open: 157, close: 156 --><font class="lisp">lsh</font><!-- open: 157, close: 157 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 158, close: 157 --><font class="lisp">rot</font><!-- open: 158, close: 158 --> <!-- MATCHED MATCHED MATCHED --> have an inherent word-length
limitation and hence only operate on 24-bit fixnums.  Negative numbers
are operated on in their 2's-complement representation.  (Negative
numbers used to be disallowed in some cases.)

<div class='defun' id='logior'>
  <font class='exdent'>
    <font class='funcname'>logior </font>
    <font class='italic' color='purple'>&rest args</font>
  </font><br>
Returns the bit-wise logical <!-- open: 159, close: 158 --><font class="italic">inclusive or</font><!-- open: 159, close: 159 --> <!-- MATCHED MATCHED MATCHED --> of its arguments.
A minimum of one argument is required.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(logior 4002 67) =&gt; 4067
</pre>
</div>

<div class='defun' id='logxor'>
  <font class='exdent'>
    <font class='funcname'>logxor </font>
    <font class='italic' color='purple'>&rest args</font>
  </font><br>
Returns the bit-wise logical <!-- open: 160, close: 159 --><font class="italic">exclusive or</font><!-- open: 160, close: 160 --> <!-- MATCHED MATCHED MATCHED --> of its arguments.
A minimum of one argument is required.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(logxor 2531 7777) =&gt; 5246
</pre>
</div>

<div class='defun' id='logand'>
  <font class='exdent'>
    <font class='funcname'>logand </font>
    <font class='italic' color='purple'>&rest args</font>
  </font><br>
Returns the bit-wise logical <!-- open: 161, close: 160 --><font class="italic">and</font><!-- open: 161, close: 161 --> <!-- MATCHED MATCHED MATCHED --> of its arguments.
A minimum of one argument is required.
<pre class='lisp'>
<font class='exdent'>Examples:
</font><!-- exdent -->(logand 3456 707) =&gt; 406
(logand 3456 -100) =&gt; 3400
</pre>
</div>

<div class='defun' id='boole'>
  <font class='exdent'>
    <font class='funcname'>boole </font>
    <font class='italic' color='purple'>fn &rest args</font>
  </font><br>
<!-- open: 162, close: 161 --><font class="lisp">boole</font><!-- open: 162, close: 162 --> <!-- MATCHED MATCHED MATCHED --> is the generalization of <!-- open: 163, close: 162 --><font class="lisp">logand</font><!-- open: 163, close: 163 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 164, close: 163 --><font class="lisp">logior</font><!-- open: 164, close: 164 --> <!-- MATCHED MATCHED MATCHED -->, and <!-- open: 165, close: 164 --><font class="lisp">logxor</font><!-- open: 165, close: 165 --> <!-- MATCHED MATCHED MATCHED -->.
<!-- open: 166, close: 165 --><font class="italic">fn</font><!-- open: 166, close: 166 --> <!-- MATCHED MATCHED MATCHED --> should be a fixnum between 0 and 17 octal inclusive;
it controls the function which is computed.  If the binary representation
of <!-- open: 167, close: 166 --><font class="italic">fn</font><!-- open: 167, close: 167 --> <!-- MATCHED MATCHED MATCHED --> is <!-- open: 168, close: 167 --><font class="italic">abcd</font><!-- open: 168, close: 168 --> <!-- MATCHED MATCHED MATCHED --> (<!-- open: 169, close: 168 --><font class="italic">a</font><!-- open: 169, close: 169 --> <!-- MATCHED MATCHED MATCHED --> is the most significant bit, <!-- open: 170, close: 169 --><font class="italic">d</font><!-- open: 170, close: 170 --> <!-- MATCHED MATCHED MATCHED --> the least)
then the truth table for the Boolean operation is as follows:
.sp
<pre class='lisp'>
       y
   | 0  1
---------
  0| a  c
x  |
  1| b  d
</pre>

If <!-- open: 171, close: 170 --><font class="lisp">boole</font><!-- open: 171, close: 171 --> <!-- MATCHED MATCHED MATCHED --> has more than three arguments, it is associated left
to right; thus,
<pre class='lisp'>
(boole fn x y z) = (boole fn (boole fn x y) z)
</pre>
With two arguments, the result of <!-- open: 172, close: 171 --><font class="lisp">boole</font><!-- open: 172, close: 172 --> <!-- MATCHED MATCHED MATCHED --> is simply its second argument.
A minimum of two arguments is required.

<pre class='lisp'>
<font class='exdent'>Examples:
</font><!-- exdent -->(boole 1 x y) = (logand x y)
(boole 6 x y) = (logxor x y)
</pre>

<!-- open: 173, close: 172 --><font class="lisp">logand</font><!-- open: 173, close: 173 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 174, close: 173 --><font class="lisp">logior</font><!-- open: 174, close: 174 --> <!-- MATCHED MATCHED MATCHED -->, and <!-- open: 175, close: 174 --><font class="lisp">logxor</font><!-- open: 175, close: 175 --> <!-- MATCHED MATCHED MATCHED --> are usually preferred over <!-- open: 176, close: 175 --><font class="lisp">boole</font><!-- open: 176, close: 176 --> <!-- MATCHED MATCHED MATCHED -->.
</div>

<div class='defun' id='bit-test'>
  <font class='exdent'>
    <font class='funcname'>bit-test </font>
    <font class='italic' color='purple'>x y</font>
  </font><br>
<!-- open: 177, close: 176 --><font class="lisp">bit-test</font><!-- open: 177, close: 177 --> <!-- MATCHED MATCHED MATCHED --> is a predicate which returns <!-- open: 178, close: 177 --><font class="lisp">t</font><!-- open: 178, close: 178 --> <!-- MATCHED MATCHED MATCHED --> if any of
the bits designated by the 1's in <!-- open: 179, close: 178 --><font class="italic">x</font><!-- open: 179, close: 179 --> <!-- MATCHED MATCHED MATCHED --> are 1's in <!-- open: 180, close: 179 --><font class="italic">y</font><!-- open: 180, close: 180 --> <!-- MATCHED MATCHED MATCHED -->.
<!-- open: 181, close: 180 --><font class="lisp">bit-test</font><!-- open: 181, close: 181 --> <!-- MATCHED MATCHED MATCHED --> is implemented as a macro which expands as follows:
<pre class='lisp'>
(bit-test <!-- open: 182, close: 181 --><font class="italic">x</font><!-- open: 182, close: 182 --> <!-- MATCHED MATCHED MATCHED --> <!-- open: 183, close: 182 --><font class="italic">y</font><!-- open: 183, close: 183 --> <!-- MATCHED MATCHED MATCHED -->) ==&gt; (not (zerop (logand <!-- open: 184, close: 183 --><font class="italic">x</font><!-- open: 184, close: 184 --> <!-- MATCHED MATCHED MATCHED --> <!-- open: 185, close: 184 --><font class="italic">y</font><!-- open: 185, close: 185 --> <!-- MATCHED MATCHED MATCHED -->)))
</pre>
</div>

<div class='defun' id='ldb-test'>
  <font class='exdent'>
    <font class='funcname'>ldb-test </font>
    <font class='italic' color='purple'>ppss y</font>
  </font><br>
<!-- open: 186, close: 185 --><font class="lisp">ldb-test</font><!-- open: 186, close: 186 --> <!-- MATCHED MATCHED MATCHED --> is a predicate which returns <!-- open: 187, close: 186 --><font class="lisp">t</font><!-- open: 187, close: 187 --> <!-- MATCHED MATCHED MATCHED --> if any of
the bits designated by the byte specifier <!-- open: 188, close: 187 --><font class="italic">ppss</font><!-- open: 188, close: 188 --> <!-- MATCHED MATCHED MATCHED --> are 1's in <!-- open: 189, close: 188 --><font class="italic">y</font><!-- open: 189, close: 189 --> <!-- MATCHED MATCHED MATCHED -->.
That is, it returns <!-- open: 190, close: 189 --><font class="lisp">t</font><!-- open: 190, close: 190 --> <!-- MATCHED MATCHED MATCHED --> if the designated field is non-zero.
<!-- open: 191, close: 190 --><font class="lisp">ldb-test</font><!-- open: 191, close: 191 --> <!-- MATCHED MATCHED MATCHED --> is implemented as a macro which expands as follows:
<pre class='lisp'>
(ldb-test <!-- open: 192, close: 191 --><font class="italic">ppss</font><!-- open: 192, close: 192 --> <!-- MATCHED MATCHED MATCHED --> <!-- open: 193, close: 192 --><font class="italic">y</font><!-- open: 193, close: 193 --> <!-- MATCHED MATCHED MATCHED -->) ==&gt; (not (zerop (ldb <!-- open: 194, close: 193 --><font class="italic">ppss</font><!-- open: 194, close: 194 --> <!-- MATCHED MATCHED MATCHED --> <!-- open: 195, close: 194 --><font class="italic">y</font><!-- open: 195, close: 195 --> <!-- MATCHED MATCHED MATCHED -->)))
</pre>
</div>

<div class='defun' id='lsh'>
  <font class='exdent'>
    <font class='funcname'>lsh </font>
    <font class='italic' color='purple'>x y</font>
  </font><br>
Returns <!-- open: 196, close: 195 --><font class="italic">x</font><!-- open: 196, close: 196 --> <!-- MATCHED MATCHED MATCHED --> shifted left <!-- open: 197, close: 196 --><font class="italic">y</font><!-- open: 197, close: 197 --> <!-- MATCHED MATCHED MATCHED --> bits if <!-- open: 198, close: 197 --><font class="italic">y</font><!-- open: 198, close: 198 --> <!-- MATCHED MATCHED MATCHED --> is positive or zero,
or <!-- open: 199, close: 198 --><font class="italic">x</font><!-- open: 199, close: 199 --> <!-- MATCHED MATCHED MATCHED --> shifted right <!-- open: 200, close: 199 --><font class="lisp">|<!-- open: 201, close: 199 --><font class="italic">y</font><!-- open: 201, close: 200 -->|</font><!-- open: 201, close: 201 --> <!-- MATCHED MATCHED MATCHED --> bits if <!-- open: 202, close: 201 --><font class="italic">y</font><!-- open: 202, close: 202 --> <!-- MATCHED MATCHED MATCHED --> is negative.
Zero bits are shifted in (at either end) to fill unused positions.
<!-- open: 203, close: 202 --><font class="italic">x</font><!-- open: 203, close: 203 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 204, close: 203 --><font class="italic">y</font><!-- open: 204, close: 204 --> <!-- MATCHED MATCHED MATCHED --> must be fixnums.
<pre class='lisp'>
<font class='exdent'>Examples:
</font><!-- exdent -->(lsh 4 1) =&gt; 10    <!-- open: 205, close: 204 --><font class="main">;(octal)</font><!-- open: 205, close: 205 --> <!-- MATCHED MATCHED MATCHED -->
(lsh 14 -2) =&gt; 3
(lsh -1 1) =&gt; -2
</pre>
</div>

<div class='defun' id='ash'>
  <font class='exdent'>
    <font class='funcname'>ash </font>
    <font class='italic' color='purple'>x y</font>
  </font><br>
Shifts <!-- open: 206, close: 205 --><font class="italic">x</font><!-- open: 206, close: 206 --> <!-- MATCHED MATCHED MATCHED --> arithmetically left <!-- open: 207, close: 206 --><font class="italic">y</font><!-- open: 207, close: 207 --> <!-- MATCHED MATCHED MATCHED --> bits, or right <!-- open: 208, close: 207 --><font class="italic">-y</font><!-- open: 208, close: 208 --> <!-- MATCHED MATCHED MATCHED --> bits,
depending on the sign of <!-- open: 209, close: 208 --><font class="italic">y</font><!-- open: 209, close: 209 --> <!-- MATCHED MATCHED MATCHED -->.  <!-- open: 210, close: 209 --><font class="italic">x</font><!-- open: 210, close: 210 --> <!-- MATCHED MATCHED MATCHED --> may be a fixnum or a bignum.
The sign of the result is always the same as the sign of <!-- open: 211, close: 210 --><font class="italic">x</font><!-- open: 211, close: 211 --> <!-- MATCHED MATCHED MATCHED -->.
</div>

<div class='defun' id='rot'>
  <font class='exdent'>
    <font class='funcname'>rot </font>
    <font class='italic' color='purple'>x y</font>
  </font><br>
Returns <!-- open: 212, close: 211 --><font class="italic">x</font><!-- open: 212, close: 212 --> <!-- MATCHED MATCHED MATCHED --> rotated left <!-- open: 213, close: 212 --><font class="italic">y</font><!-- open: 213, close: 213 --> <!-- MATCHED MATCHED MATCHED --> bits if <!-- open: 214, close: 213 --><font class="italic">y</font><!-- open: 214, close: 214 --> <!-- MATCHED MATCHED MATCHED --> is positive or zero,
or <!-- open: 215, close: 214 --><font class="italic">x</font><!-- open: 215, close: 215 --> <!-- MATCHED MATCHED MATCHED --> rotated right <!-- open: 216, close: 215 --><font class="lisp">|<!-- open: 217, close: 215 --><font class="italic">y</font><!-- open: 217, close: 216 -->|</font><!-- open: 217, close: 217 --> <!-- MATCHED MATCHED MATCHED --> bits if <!-- open: 218, close: 217 --><font class="italic">y</font><!-- open: 218, close: 218 --> <!-- MATCHED MATCHED MATCHED --> is negative.
The rotation considers <!-- open: 219, close: 218 --><font class="italic">x</font><!-- open: 219, close: 219 --> <!-- MATCHED MATCHED MATCHED --> as a 24-bit number (unlike Maclisp,
which considers <!-- open: 220, close: 219 --><font class="italic">x</font><!-- open: 220, close: 220 --> <!-- MATCHED MATCHED MATCHED --> to be a 36-bit number in both the pdp-10
and Multics implementations).
<!-- open: 221, close: 220 --><font class="italic">x</font><!-- open: 221, close: 221 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 222, close: 221 --><font class="italic">y</font><!-- open: 222, close: 222 --> <!-- MATCHED MATCHED MATCHED --> must be fixnums.
<pre class='lisp'>
<font class='exdent'>Examples:
</font><!-- exdent -->(rot 1 2) =&gt; 4
(rot 1 -2) =&gt; 20000000
(rot -1 7) =&gt; -1
(rot 15 24.) =&gt; 15
</pre>
</div>

<div class='defun' id='haipart'>
  <font class='exdent'>
    <font class='funcname'>haipart </font>
    <font class='italic' color='purple'>x n</font>
  </font><br>
Returns the high <!-- open: 223, close: 222 --><font class="italic">n</font><!-- open: 223, close: 223 --> <!-- MATCHED MATCHED MATCHED --> bits of the binary representation of <!-- open: 224, close: 223 --><font class="lisp">|<!-- open: 225, close: 223 --><font class="italic">x</font><!-- open: 225, close: 224 -->|</font><!-- open: 225, close: 225 --> <!-- MATCHED MATCHED MATCHED -->,
or the low <!-- open: 226, close: 225 --><font class="lisp">|<!-- open: 227, close: 225 --><font class="italic">n</font><!-- open: 227, close: 226 -->|</font><!-- open: 227, close: 227 --> <!-- MATCHED MATCHED MATCHED --> bits if <!-- open: 228, close: 227 --><font class="italic">n</font><!-- open: 228, close: 228 --> <!-- MATCHED MATCHED MATCHED --> is negative.
<!-- open: 229, close: 228 --><font class="italic">x</font><!-- open: 229, close: 229 --> <!-- MATCHED MATCHED MATCHED --> may be a fixnum or a bignum; note that if <!-- open: 230, close: 229 --><font class="italic">x</font><!-- open: 230, close: 230 --> <!-- MATCHED MATCHED MATCHED --> is negative
its absolute value is used.
<!-- Is there a better description of this in the Maclisp manual? -->
</div>

<div class='defun' id='haulong'>
  <font class='exdent'>
    <font class='funcname'>haulong </font>
    <font class='italic' color='purple'>x</font>
  </font><br>
This returns the number of significant bits in <!-- open: 231, close: 230 --><font class="italic">x</font><!-- open: 231, close: 231 --> <!-- MATCHED MATCHED MATCHED -->.  <!-- open: 232, close: 231 --><font class="italic">x</font><!-- open: 232, close: 232 --> <!-- MATCHED MATCHED MATCHED --> may be a fixnum or a bignum.
The result does not depend on the sign of <!-- open: 233, close: 232 --><font class="italic">x</font><!-- open: 233, close: 233 --> <!-- MATCHED MATCHED MATCHED -->.
The result is the least integer not less than the base-2 logarithm of <!-- open: 234, close: 233 --><font class="lisp">|<!-- open: 235, close: 233 --><font class="italic">x</font><!-- open: 235, close: 234 -->|+1</font><!-- open: 235, close: 235 --> <!-- MATCHED MATCHED MATCHED -->.
<pre class='lisp'>
<font class='exdent'>Examples:
</font><!-- exdent -->(haulong 0) =&gt; 0
(haulong 3) =&gt; 2
(haulong -7) =&gt; 3
</pre>
</div>

<div class='section' id='9.5'>9.5 Byte Manipulation Functions</div><p class='cindent'><!-- "byte" -->
Several functions are provided for dealing with an arbitrary-width field of
contiguous bits appearing anywhere in an integer (a fixnum or a bignum).
Such a contiguous set of bits is called a <!-- open: 236, close: 235 --><font class="italic">byte</font><!-- open: 236, close: 236 --> <!-- MATCHED MATCHED MATCHED -->.  Note that
we are not using the term <!-- open: 237, close: 236 --><font class="italic">byte</font><!-- open: 237, close: 237 --> <!-- MATCHED MATCHED MATCHED --> to mean eight bits, but rather
any number of bits within a number.
These functions use numbers called <!-- open: 238, close: 237 --><font class="italic">byte specifiers</font><!-- open: 238, close: 238 --> <!-- MATCHED MATCHED MATCHED --> to
<p class='cindent'><!-- "byte specifiers" -->
designate a specific byte position within any word.  Byte specifiers are fixnums
whose two lowest octal digits represent the <!-- open: 239, close: 238 --><font class="italic">size</font><!-- open: 239, close: 239 --> <!-- MATCHED MATCHED MATCHED --> of the
byte, and whose higher (usually two, but sometimes more)
octal digits represent the <!-- open: 240, close: 239 --><font class="italic">position</font><!-- open: 240, close: 240 --> <!-- MATCHED MATCHED MATCHED -->
of the byte within a number, counting from the right in bits.  A position
of zero means that the byte is at the right end of the number.
For example, the byte-specifier 0010 (i.e., 10 octal) refers to the lowest 
eight bits of a word, and the byte-specifier 1010 refers to the next eight
bits.  These byte-specifiers will be stylized below as <!-- open: 241, close: 240 --><font class="italic">ppss</font><!-- open: 241, close: 241 --> <!-- MATCHED MATCHED MATCHED -->.
<p class='cindent'><!-- "ppss" -->
The maximum value of the <!-- open: 242, close: 241 --><font class="italic">ss</font><!-- open: 242, close: 242 --> <!-- MATCHED MATCHED MATCHED --> digits is 27 (octal), since a byte must
fit in a fixnum although bytes can be loaded from and deposited into bignums.
(Bytes are always positive numbers.)
The format of byte-specifiers is taken from the pdp-10 byte instructions.

<div class='defun' id='ldb'>
  <font class='exdent'>
    <font class='funcname'>ldb </font>
    <font class='italic' color='purple'>ppss num </font>
  </font><br>
<!-- open: 243, close: 242 --><font class="italic">ppss</font><!-- open: 243, close: 243 --> <!-- MATCHED MATCHED MATCHED --> specifies a byte of <!-- open: 244, close: 243 --><font class="italic">num</font><!-- open: 244, close: 244 --> <!-- MATCHED MATCHED MATCHED -->, which is returned as a number,
right-justified.  The <!-- open: 245, close: 244 --><font class="italic">ss</font><!-- open: 245, close: 245 --> <!-- MATCHED MATCHED MATCHED --> bits of the byte starting at bit <!-- open: 246, close: 245 --><font class="italic">pp</font><!-- open: 246, close: 246 --> <!-- MATCHED MATCHED MATCHED -->
are the lowest <!-- open: 247, close: 246 --><font class="italic">ss</font><!-- open: 247, close: 247 --> <!-- MATCHED MATCHED MATCHED --> bits in the returned value, and the rest of the
bits in the returned value are zero.  The name of the function,
<!-- open: 248, close: 247 --><font class="lisp">ldb</font><!-- open: 248, close: 248 --> <!-- MATCHED MATCHED MATCHED -->, means "load byte".  <!-- open: 249, close: 248 --><font class="italic">num</font><!-- open: 249, close: 249 --> <!-- MATCHED MATCHED MATCHED --> may be a fixnum or a bignum.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(ldb 0306 4567) =&gt; 56
</pre>
</div>

<div class='defun' id='mask-field'>
  <font class='exdent'>
    <font class='funcname'>mask-field </font>
    <font class='italic' color='purple'>ppss num</font>
  </font><br>
This is similar to <!-- open: 250, close: 249 --><font class="lisp">ldb</font><!-- open: 250, close: 250 --> <!-- MATCHED MATCHED MATCHED -->; however, the specified byte
of <!-- open: 251, close: 250 --><font class="italic">num</font><!-- open: 251, close: 251 --> <!-- MATCHED MATCHED MATCHED --> is returned as a number in position <!-- open: 252, close: 251 --><font class="italic">pp</font><!-- open: 252, close: 252 --> <!-- MATCHED MATCHED MATCHED --> of
the returned word, instead of position 0 as with <!-- open: 253, close: 252 --><font class="lisp">ldb</font><!-- open: 253, close: 253 --> <!-- MATCHED MATCHED MATCHED -->.
<!-- open: 254, close: 253 --><font class="italic">num</font><!-- open: 254, close: 254 --> <!-- MATCHED MATCHED MATCHED --> must be a fixnum.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(mask-field 0306 4567) =&gt; 560
</pre>
</div>

<div class='defun' id='dpb'>
  <font class='exdent'>
    <font class='funcname'>dpb </font>
    <font class='italic' color='purple'>byte ppss num</font>
  </font><br>
Returns a number which is the same as <!-- open: 255, close: 254 --><font class="italic">num</font><!-- open: 255, close: 255 --> <!-- MATCHED MATCHED MATCHED --> except in the
bits specified by <!-- open: 256, close: 255 --><font class="italic">ppss</font><!-- open: 256, close: 256 --> <!-- MATCHED MATCHED MATCHED -->.  The low
<!-- open: 257, close: 256 --><font class="italic">ss</font><!-- open: 257, close: 257 --> <!-- MATCHED MATCHED MATCHED --> bits of <!-- open: 258, close: 257 --><font class="italic">byte</font><!-- open: 258, close: 258 --> <!-- MATCHED MATCHED MATCHED --> are placed in those bits.  <!-- open: 259, close: 258 --><font class="italic">byte</font><!-- open: 259, close: 259 --> <!-- MATCHED MATCHED MATCHED --> is interpreted as
being right-justified, as if it were the result of <!-- open: 260, close: 259 --><font class="lisp">ldb</font><!-- open: 260, close: 260 --> <!-- MATCHED MATCHED MATCHED -->.
<!-- open: 261, close: 260 --><font class="italic">num</font><!-- open: 261, close: 261 --> <!-- MATCHED MATCHED MATCHED --> may be a fixnum or a bignum.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(dpb 23 0306 4567) =&gt; 4237
</pre>
</div>

<div class='defun' id='deposit-field'>
  <font class='exdent'>
    <font class='funcname'>deposit-field </font>
    <font class='italic' color='purple'>byte ppss num</font>
  </font><br>
This is like <!-- open: 262, close: 261 --><font class="lisp">dpb</font><!-- open: 262, close: 262 --> <!-- MATCHED MATCHED MATCHED -->, except that <!-- open: 263, close: 262 --><font class="italic">byte</font><!-- open: 263, close: 263 --> <!-- MATCHED MATCHED MATCHED --> is not taken to
be left-justified; the <!-- open: 264, close: 263 --><font class="italic">ppss</font><!-- open: 264, close: 264 --> <!-- MATCHED MATCHED MATCHED --> bits of <!-- open: 265, close: 264 --><font class="italic">byte</font><!-- open: 265, close: 265 --> <!-- MATCHED MATCHED MATCHED --> are used
for the <!-- open: 266, close: 265 --><font class="italic">ppss</font><!-- open: 266, close: 266 --> <!-- MATCHED MATCHED MATCHED --> bits of the result, with the rest of the
bits taken from <!-- open: 267, close: 266 --><font class="italic">num</font><!-- open: 267, close: 267 --> <!-- MATCHED MATCHED MATCHED -->.  <!-- open: 268, close: 267 --><font class="italic">num</font><!-- open: 268, close: 268 --> <!-- MATCHED MATCHED MATCHED --> must be a fixnum.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(deposit-field 230 0306 4567) =&gt; 4237
</pre>
</div>

<div class='defun' id='%logldb'>
  <font class='exdent'>
    <font class='funcname'>%logldb </font>
    <font class='italic' color='purple'>ppss fixnum</font>
  </font><br>
<!-- open: 269, close: 268 --><font class="lisp">%logldb</font><!-- open: 269, close: 269 --> <!-- MATCHED MATCHED MATCHED --> is like <!-- open: 270, close: 269 --><font class="lisp">ldb</font><!-- open: 270, close: 270 --> <!-- MATCHED MATCHED MATCHED --> except that it only loads out of fixnums and
allows a byte size of 30 (octal), i.e. the whole fixnum.
</div>

<div class='defun' id='%logdpb'>
  <font class='exdent'>
    <font class='funcname'>%logdpb </font>
    <font class='italic' color='purple'>byte ppss fixnum</font>
  </font><br>
<!-- open: 271, close: 270 --><font class="lisp">%logdpb</font><!-- open: 271, close: 271 --> <!-- MATCHED MATCHED MATCHED --> is like <!-- open: 272, close: 271 --><font class="lisp">dpb</font><!-- open: 272, close: 272 --> <!-- MATCHED MATCHED MATCHED --> except that it only deposits into fixnums.
Using this to change the sign-bit will leave the result as a fixnum,
while <!-- open: 273, close: 272 --><font class="lisp">dpb</font><!-- open: 273, close: 273 --> <!-- MATCHED MATCHED MATCHED --> would produce a bignum result for arithmetic correctness.
<!-- open: 274, close: 273 --><font class="lisp">%logdpb</font><!-- open: 274, close: 274 --> <!-- MATCHED MATCHED MATCHED --> is good for manipulating fixnum bit-masks such as are used
in some internal system tables and data-structures.
</div>

<div class='section' id='9.6'>9.6 24-Bit Numbers</div>Sometimes it is desirable to have a form of arithmetic which has no
overflow checking (which would produce bignums),
and truncates results to the word size of the machine.
In Lisp Machine Lisp, this is provided by the following set of functions.
Their answers are only correct modulo 2^24.
	These functions should <!-- open: 275, close: 274 --><font class="italic">not</font><!-- open: 275, close: 275 --> <!-- MATCHED MATCHED MATCHED --> be used for "efficiency";
they are probably less efficient than the functions which <!-- open: 276, close: 275 --><font class="italic">do</font><!-- open: 276, close: 276 --> <!-- MATCHED MATCHED MATCHED --> check for
overflow.  They are intended for algorithms which require this sort of
arithmetic, such as hash functions and pseudo-random number generation.

<div class='defun' id='%24-bit-plus'>
  <font class='exdent'>
    <font class='funcname'>%24-bit-plus </font>
    <font class='italic' color='purple'>x y</font>
  </font><br>
Returns the sum of <!-- open: 277, close: 276 --><font class="italic">x</font><!-- open: 277, close: 277 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 278, close: 277 --><font class="italic">y</font><!-- open: 278, close: 278 --> <!-- MATCHED MATCHED MATCHED --> modulo 2^24.  Both arguments should
be fixnums.
</div>

<div class='defun' id='%24-bit-difference'>
  <font class='exdent'>
    <font class='funcname'>%24-bit-difference </font>
    <font class='italic' color='purple'>x y</font>
  </font><br>
Returns the difference of <!-- open: 279, close: 278 --><font class="italic">x</font><!-- open: 279, close: 279 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 280, close: 279 --><font class="italic">y</font><!-- open: 280, close: 280 --> <!-- MATCHED MATCHED MATCHED --> modulo 2^24.  Both arguments should
be fixnums.
</div>

<div class='defun' id='%24-bit-times'>
  <font class='exdent'>
    <font class='funcname'>%24-bit-times </font>
    <font class='italic' color='purple'>x y</font>
  </font><br>
Returns the product of <!-- open: 281, close: 280 --><font class="italic">x</font><!-- open: 281, close: 281 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 282, close: 281 --><font class="italic">y</font><!-- open: 282, close: 282 --> <!-- MATCHED MATCHED MATCHED --> modulo 2^24.  Both arguments should
be fixnums.
</div>

<div class='section' id='9.7'>9.7 Double-Precision Arithmetic</div>
These peculiar functions are useful in programs that don't want to use
bignums for one reason or another.

<div class='defun' id='%multiply-fractions'>
  <font class='exdent'>
    <font class='funcname'>%multiply-fractions </font>
    <font class='italic' color='purple'>num1 num2</font>
  </font><br>
Returns bits 24 through 46 (the most significant half)
of the product of <!-- open: 283, close: 282 --><font class="italic">num1</font><!-- open: 283, close: 283 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 284, close: 283 --><font class="italic">num2</font><!-- open: 284, close: 284 --> <!-- MATCHED MATCHED MATCHED -->.
If you call this and <!-- open: 285, close: 284 --><font class="lisp">%24-bit-times</font><!-- open: 285, close: 285 --> <!-- MATCHED MATCHED MATCHED --> on the same arguments <!-- open: 286, close: 285 --><font class="italic">num1</font><!-- open: 286, close: 286 --> <!-- MATCHED MATCHED MATCHED -->
and <!-- open: 287, close: 286 --><font class="italic">num2</font><!-- open: 287, close: 287 --> <!-- MATCHED MATCHED MATCHED -->, regarding them as integers, you can combine
the results into a double-precision product.
If <!-- open: 288, close: 287 --><font class="italic">num1</font><!-- open: 288, close: 288 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 289, close: 288 --><font class="italic">num2</font><!-- open: 289, close: 289 --> <!-- MATCHED MATCHED MATCHED --> are regarded as fractions, <!-- open: 290, close: 289 --><font class="lisp">-1 &le; <!-- open: 291, close: 289 --><font class="italic">num</font><!-- open: 291, close: 290 --> &lt; 1</font><!-- open: 291, close: 291 --> <!-- MATCHED MATCHED MATCHED -->,
<!-- open: 292, close: 291 --><font class="lisp">%multiply-fractions</font><!-- open: 292, close: 292 --> <!-- MATCHED MATCHED MATCHED --> returns 1/2 of their correct product as a fraction.
(The name of this function isn't too great.)
</div>

<div class='defun' id='%divide-double'>
  <font class='exdent'>
    <font class='funcname'>%divide-double </font>
    <font class='italic' color='purple'>dividend[24:46] dividend[0:23] divisor</font>
  </font><br>
Divides the double-precision number given by the first two
arguments by the third argument, and returns the single-precision
quotient.  Causes an error if division by zero or if the quotient won't
fit in single precision.
</div>

<div class='defun' id='%remainder-double'>
  <font class='exdent'>
    <font class='funcname'>%remainder-double </font>
    <font class='italic' color='purple'>dividend[24:46] dividend[0:23] divisor</font>
  </font><br>
Divides the double-precision number given by the first two
arguments by the third argument, and returns the
remainder.  Causes an error if division by zero.
</div>

<div class='defun' id='%float-double'>
  <font class='exdent'>
    <font class='funcname'>%float-double </font>
    <font class='italic' color='purple'>high24 low24</font>
  </font><br>
<!-- open: 293, close: 292 --><font class="italic">high24</font><!-- open: 293, close: 293 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 294, close: 293 --><font class="italic">low24</font><!-- open: 294, close: 294 --> <!-- MATCHED MATCHED MATCHED -->, which must be fixnums, are concatenated
to produce a 48-bit unsigned positive integer.  A flonum containing the
same value is constructed and returned.  Note that only the 31 most-significant
bits are retained (after removal of leading zeroes.)  This function is
mainly for the benefit of <!-- open: 295, close: 294 --><font class="lisp">read</font><!-- open: 295, close: 295 --> <!-- MATCHED MATCHED MATCHED -->.
</div>

<!-- eof -->
</body>
</html>

